The Mule Client is a simple interface for java clients to send and receive events from a Mule Server and other applications. The client serves the following functions -

• Sending and receiving events to/from a local mule server
• Sending and receiving events to/from a remote mule server
• Communicating with other applications using any Mule transport
• Registering and unregistering components in a Mule server

Using Send and Dispatch

In most Mule applications events are triggered by some external occurrence such as a message being received on a queue or file being copied to a directory. The Mule client allows the user to send and receive events programmatically. For example, to send a Jms message to any application, Mule component or otherwise, listening on my.queue -

MuleClient client = new MuleClient();
client.dispatch("jms://my.queue", "Message Payload" null);

To make a regular client/server synchronous call the send() method can be used -

MuleClient client = new MuleClient();
UMOMessage result = client.send("tcp://localhost:3456", 
                                 "Message Payload", null);

Making synchronous calls asynchronously

Mule Client allows you to make synchronous calls without blocking using the sendAsync() method.

MuleClient client = new MuleClient();
FutureMessageResult result = client.sendAsync("http://localhost:8881", 
                                 "Message Payload", null);
//Do some more stuff here

if(result.isready()) {
    Object payload = result.getMessage().getPayload();
}

The client send(), sendAsync() and dispatch() methods expect 3 arguments -

1. The mule url endpoint - This is any valid Mule Endpoint used to determine the transport, endpoint and other information about delivery of the event
2. The event payload - this can be any object
3. Properties - any properties or meta-data to associate with the event

MuleClient as a Web Services Client

The Mule client can be used as a web services client to make soap requests using popular soap implementations such as Web Methods Glue and Apache Axis.

MuleClient client = new MuleClient();

//Arguments for the addPerson WS method
String[] args = new String[]{"Ross", "Mason"};

//Call the web service
client.dispatch("axis:http://localhost:38004/PersonService?method=addPerson", args, null);

//Call another method to look up the newly added person
UMOMessage result = client.send
        ("axis:http://localhost:38004/PersonService?method=getPerson", "Ross", null);

//A person object is returned and all type mapping is handled for you
Person person (Person)result.getPayload();

System.out.println(person.toString());

Soap Provider The Mule Soap Provider supports Web Methods Glue and Apache Axis. For more information about Mule Axis support go here, for more information about MUle Glue support go here.

Performing Request-Response calls

To receive events the client has a receive method, i.e.

MuleClient client = new MuleClient();
UMOMessage result = client.receive("pop3://ross:[email protected]", 5000);

This will attempt to receive a message from a mailbox called ross on mail.muleumo.org and will return after 5 seconds if no message was received.

Tip Calling receive() will work for all Mule supported transports, but it is more usual to make request-response calls where there is a store to be queried such as a queue, file directory, or some other repository or where a call will be executed based on the receive and a result returned such as making a soap call.

Sending events to components directly

The client also provides a convenient way to send an event directly to a component without needing to use a provider, this can be very useful in testing, but also when triggering events from a Jsp page or script. To dispatch an event directly to your stock quote component called StockManager you would do the following -

MuleClient client = new MuleClient();
UMOMessage result = client.sendDirect("StockManager", null, "give me the price of XXX", null);

StockQuote sq = (StockQuote)result.getPayload();

Note that the call is sendDirect, this tells the client to go directly to the component and not through a provider. As such there will be no transformers configured for this call. You can specify a comma-separated list of transformers to use in the second argument of this call.

The Client Remote Dispatcher

The client can connect to, send and receive events from a remote Mule server. using the previous example -

MuleClient client = new MuleClient();
RemoteDispatcher dispatcher = client.getRemoteDispatcher("tcp://localhost:60504");
UMOMessage result = dispatcher.sendRemote("StockManager", null, "give me the price of XXX", null);

StockQuote sq = (StockQuote)result.getPayload();

The Mule client will execute the StockManager component on a remote Mule server, returning the result to the client. Mule handles all the call marshalling. The first null argument is a optional string of comma separated transformers to use on the result message. The second null argument is properties associated with the request.

Often you will not want to wait for the result to be returned from the remote server, so you can use the asyncRemote() method that returns a FutureMessageResult.

MuleClient client = new MuleClient();
RemoteDispatcher dispatcher = client.getRemoteDispatcher("tcp://localhost:60504");
FutureMessageResult result = dispatcher.asyncRemote("StockManager", null, 
                                         "give me the price of XXX", null);

//do some other stuff

StockQuote sq = (StockQuote)result.getMessage(1000).getPayload();

The result returned is a placeholder for the real result message when the call returns. By using a future result you can continue with other tasks while the remote call executes. Calling getMessage() will block until the call returns. Optionally you can specify a timeout of how long to wait (shown in the example). You can also check if the call has returned using result.isReady().

By default, the Mule server will listen on tcp://localhost:60504, if you want the client to use a different server location you can specify it when you create the remote dispatcher-

MuleClient client = new MuleClient();
RemoteDispatcher dispatcher = client.getRemoteDispatcher("http://228.8.9.10:6677");

Configuring the MuleManager

When the manager is running asynchronous, making a synchronous client call i.e. client.send(..) the result event will always be null, as internally, Mule will be making all calls asynchronously. You can determine if Mule is running synchronously by calling -

boolean sync = MuleManager.getConfiguration().isSynchronous();

Associating properties with the Message

So far in all the examples we have set the properties argument to null. Properties can be arbitrary, i.e. to pass around custom meta-data with your events or they can be transport specific. The following example demonstrates an asynchronous request/response using Jms and the Jms specific JMSReplyTo property.

//create the client instance
MuleClient client = new MuleClient();

//create properties to associate with the event
Map props = new HashMap();

//Set the JMSReplyTo property, this is where the response message will be sent
props.put("JMSReplyTo", "replyTo.queue");

//dispatch our message asynchronously
client.dispatch("jms://test.queue", "Test Client Dispatch message", props);

//Receive the return message on the replyTo.queue
UMOMessage message = client.receive("jms://replyTo.queue", 5000);

//This the message sent back from the first component to process our event
System.out.println(message.getPayload());

This example demonstrates how to send a mail message using the client and setting the subject and and from address as properties on call.

Tip The Mule Client doesn't have to be used to talk to a Mule Server. It doesn't matter what application is receiving requests made by the client.

//create the client instance
MuleClient client = new MuleClient();

//create properties to associate with the event
Map props = new HashMap();

//Set the Subject and From address property. These properties are defined by the [Smtp Provider].

props.put("subject", "A message from mule");
props.put("fromAddress", "[email protected]");

//dispatch our message asynchronously
client.dispatch("smtp://ross:[email protected]?
          [email protected]", "Test Client Dispatch message", props);

Or to omit the smtp connection information from the url you can configure an smtp connector in Mule and just use -

client.dispatch("smtp://[email protected]", "Test Client Dispatch message", props);